Summary

• Add controls.cloned_from_control_id plus cloned=true|false filtering on GET /api/v1/controls.
• Add POST /api/v1/controls/{control_id}/clone-and-bind to clone an active control and create a target binding in one transaction.
• Add optional attachment expansion on GET /api/v1/controls for direct agents, policies, and target bindings, including each control's action.
• Apply attachment_target_type / attachment_target_id filters before list pagination, so callers can list controls attached to a specific target.
• Add PATCH /api/v1/control-bindings/by-key so target-scoped callers can enable or disable an existing binding without knowing the binding ID.
• Distinguish unexpected authorization-upstream 4xx responses as AUTH_UPSTREAM_REJECTED instead of reporting them as local auth misconfiguration.
• Update Python and generated TypeScript SDK surfaces with server and SDK tests.

Usage

Clone a control and bind the clone to a target:

POST /api/v1/controls/{control_id}/clone-and-bind

{
  "name": "optional-clone-name",
  "target_binding": {
    "target_type": "environment",
    "target_id": "prod",
    "enabled": true
  }
}

{
  "id": 42,
  "name": "optional-clone-name",
  "cloned_from_control_id": 7,
  "binding_id": 99
}

List root controls or cloned controls:

GET /api/v1/controls?cloned=false
GET /api/v1/controls?cloned=true

List controls with page-scoped attachment details:

GET /api/v1/controls?include_attachments=true

List controls attached to a specific target:

GET /api/v1/controls?include_attachments=true&attachment_target_type=environment&attachment_target_id=prod

When target filters are provided, the control list is filtered before pagination, and each returned control's attachments.targets is filtered to the same target.

Each expanded control includes the normal control details, action, and optional attachments:

{
  "id": 42,
  "name": "example-control",
  "description": "Example control",
  "action": {
    "decision": "deny",
    "steering_context": null
  },
  "attachments": {
    "agents": [{ "agent_name": "example-agent" }],
    "policies": [{ "policy_id": 42 }],
    "targets": [
      {
        "binding_id": 123,
        "target_type": "environment",
        "target_id": "prod",
        "enabled": true
      }
    ]
  }
}

Enable or disable an existing target binding by natural key:

PATCH /api/v1/control-bindings/by-key

{
  "target_type": "environment",
  "target_id": "prod",
  "control_id": 42,
  "enabled": false
}

{
  "success": true,
  "enabled": false
}

This PATCH route updates only existing bindings. It returns CONTROL_BINDING_NOT_FOUND instead of creating a missing binding.

For full target-binding pagination/filtering, callers can continue using GET /api/v1/control-bindings.

Validation

• make models-test
• make server-test
• make sdk-test
• uv run --package agent-control-models ruff check --config pyproject.toml models/src
• uv run --package agent-control-server ruff check --config pyproject.toml server/src
• uv run --package agent-control ruff check --config pyproject.toml sdks/python/src
• uv run --package agent-control-models mypy --config-file pyproject.toml models/src
• uv run --package agent-control-server mypy --config-file pyproject.toml server/src
• uv run --package agent-control mypy --config-file pyproject.toml sdks/python/src
• make sdk-ts-typecheck
• make sdk-ts-name-check
• make sdk-ts-generate-check